IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/g_man/cat3/OpenGL-ftn/fglcopypixels.z/fglcopypixels

Text File | 2002-10-03 | 22.8 KB | 344 lines

ffffggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss((((3333GGGG))))              OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee              ffffggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss((((3333GGGG))))



NNNNAAAAMMMMEEEE
     ffffggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss - copy pixels in the frame buffer


FFFFOOOORRRRTTTTRRRRAAAANNNN SSSSPPPPEEEECCCCIIIIFFFFIIIICCCCAAAATTTTIIIIOOOONNNN
     SUBROUTINE ffffggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss( INTEGER*4 _x,
                               INTEGER*4 _y,
                               INTEGER*4 _w_i_d_t_h,
                               INTEGER*4 _h_e_i_g_h_t,
                               INTEGER*4 _t_y_p_e )


PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
     _x, _y Specify the window coordinates of the lower left corner of the
          rectangular region of pixels to be copied.

     _w_i_d_t_h, _h_e_i_g_h_t
          Specify the dimensions of the rectangular region of pixels to be
          copied.  Both must be nonnegative.

     _t_y_p_e Specifies whether color values, depth values, or stencil values are
          to be copied.  Symbolic constants GGGGLLLL____CCCCOOOOLLLLOOOORRRR, GGGGLLLL____DDDDEEEEPPPPTTTTHHHH, and GGGGLLLL____SSSSTTTTEEEENNNNCCCCIIIILLLL
          are accepted.

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     ffffggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss copies a screen-aligned rectangle of pixels from the
     specified frame buffer location to a region relative to the current
     raster position.  Its operation is well defined only if the entire pixel
     source region is within the exposed portion of the read window associated
     with the current context.  Results of copies from outside the window, or
     from regions of the window that are not exposed, are hardware dependent
     and undefined.

     _x and _y specify the window coordinates of the lower left corner of the
     rectangular region to be copied.  _w_i_d_t_h and _h_e_i_g_h_t specify the dimensions
     of the rectangular region to be copied.  Both _w_i_d_t_h and _h_e_i_g_h_t must not
     be negative.

     Several parameters control the processing of the pixel data while it is
     being copied.  These parameters are set with three commands:
     ffffggggllllPPPPiiiixxxxeeeellllTTTTrrrraaaannnnssssffffeeeerrrr, ffffggggllllPPPPiiiixxxxeeeellllMMMMaaaapppp, and ffffggggllllPPPPiiiixxxxeeeellllZZZZoooooooommmm.  The state of
     GGGGLLLL____IIIINNNNTTTTEEEERRRRLLLLAAAACCCCEEEE____SSSSGGGGIIIIXXXX and GGGGLLLL____IIIINNNNTTTTEEEERRRRLLLLAAAACCCCEEEE____RRRREEEEAAAADDDD____IIIINNNNGGGGRRRR, controlled by ffffggggllllEEEEnnnnaaaabbbblllleeee and
     ffffggggllllDDDDiiiissssaaaabbbblllleeee, also affect the result of ffffggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss.  This reference page
     describes the effects on ffffggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss of most, but not all, of these
     parameters.  In addition the convolution, histogram, and minmax
     operations may affect the result of ffffggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss.  See the reference
     pages for ffffggggllllCCCCoooonnnnvvvvoooolllluuuuttttiiiioooonnnnFFFFiiiilllltttteeeerrrr2222DDDDEEEEXXXXTTTT, ffffggggllllHHHHiiiissssttttooooggggrrrraaaammmmEEEEXXXXTTTT, and ffffggggllllMMMMiiiinnnnmmmmaaaaxxxxEEEEXXXXTTTT
     for more information.

     ffffggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss copies values from each pixel with the lower left-hand
     corner at (_x + i, _y + j) for 0 _< i < _w_i_d_t_h and 0 _< j < _h_e_i_g_h_t.  This
     pixel is said to be the ith pixel in the jth row. Pixels are copied in



                                                                        PPPPaaaaggggeeee 1111






ffffggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss((((3333GGGG))))              OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee              ffffggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss((((3333GGGG))))



     row order from the lowest to the highest row, left to right in each row.

     _t_y_p_e specifies whether color, depth, or stencil data is to be copied.
     The details of the transfer for each data type are as follows:

     GGGGLLLL____CCCCOOOOLLLLOOOORRRR       Indices or RGBA colors are read from the buffer currently
                    specified as the read source buffer (see ffffggggllllRRRReeeeaaaaddddBBBBuuuuffffffffeeeerrrr).
                    If the GL is in color index mode, each index that is read
                    from this buffer is converted to a fixed-point format with
                    an unspecified number of bits to the right of the binary
                    point.  Each index is then shifted left by GGGGLLLL____IIIINNNNDDDDEEEEXXXX____SSSSHHHHIIIIFFFFTTTT
                    bits, and added to GGGGLLLL____IIIINNNNDDDDEEEEXXXX____OOOOFFFFFFFFSSSSEEEETTTT.  If GGGGLLLL____IIIINNNNDDDDEEEEXXXX____SSSSHHHHIIIIFFFFTTTT is
                    negative, the shift is to the right.  In either case, zero
                    bits fill otherwise unspecified bit locations in the
                    result.  If GGGGLLLL____MMMMAAAAPPPP____CCCCOOOOLLLLOOOORRRR is true, the index is replaced
                    with the value that it references in lookup table
                    GGGGLLLL____PPPPIIIIXXXXEEEELLLL____MMMMAAAAPPPP____IIII____TTTTOOOO____IIII.  Whether the lookup replacement of
                    the index is done or not, the integer part of the index is
                                     b
                    then ANDed with 2 -1, where b is the number of bits in a
                    color index buffer.

                    If the GL is in RGBA mode, the red, green, blue, and alpha
                    components of each pixel that is read are converted to an
                    internal floating-point format with unspecified precision.
                    The conversion maps the largest representable component
                    value to 1.0, and component value 0 to 0.0.  The resulting
                    floating-point color values are then multiplied by
                    GGGGLLLL____cccc____SSSSCCCCAAAALLLLEEEE and added to GGGGLLLL____cccc____BBBBIIIIAAAASSSS, where _c is RED, GREEN,
                    BLUE, and ALPHA for the respective color components.  The
                    results are clamped to the range [0,1].  If GGGGLLLL____MMMMAAAAPPPP____CCCCOOOOLLLLOOOORRRR
                    is true, each color component is scaled by the size of
                    lookup table GGGGLLLL____PPPPIIIIXXXXEEEELLLL____MMMMAAAAPPPP____cccc____TTTTOOOO____cccc, then replaced by the
                    value that it references in that table.  _c is R, G, B, or
                    A.

                    If the GGGGLLLL____AAAARRRRBBBB____iiiimmmmaaaaggggiiiinnnngggg extension is supported, the color
                    values may be additionally processed by color-table
                    lookups, color-matrix transformations, and convolution
                    filters.

                    The GL then converts the resulting indices or RGBA colors
                    to fragments by attaching the current raster position _z
                    coordinate and texture coordinates to each pixel, then
                    assigning window coordinates (x  + i,y  + j), where
                                                   r      r
                    (x ,y ) is the current raster position, and the pixel was
                      r  r
                    the ith pixel in the jth row.  These pixel fragments are
                    then treated just like the fragments generated by
                    rasterizing points, lines, or polygons.  Texture mapping,
                    fog, and all the fragment operations are applied before
                    the fragments are written to the frame buffer.





                                                                        PPPPaaaaggggeeee 2222






ffffggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss((((3333GGGG))))              OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee              ffffggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss((((3333GGGG))))



     GGGGLLLL____DDDDEEEEPPPPTTTTHHHH       Depth values are read from the depth buffer and converted
                    directly to an internal floating-point format with
                    unspecified precision.  The resulting floating-point depth
                    value is then multiplied by GGGGLLLL____DDDDEEEEPPPPTTTTHHHH____SSSSCCCCAAAALLLLEEEE and added to
                    GGGGLLLL____DDDDEEEEPPPPTTTTHHHH____BBBBIIIIAAAASSSS.  The result is clamped to the range [0,1].

                    The GL then converts the resulting depth components to
                    fragments by attaching the current raster position color
                    or color index and texture coordinates to each pixel, then
                    assigning window coordinates (x  + i,y  + j), where
                                                   r      r
                    (x ,y ) is the current raster position, and the pixel was
                      r  r
                    the ith pixel in the jth row.  These pixel fragments are
                    then treated just like the fragments generated by
                    rasterizing points, lines, or polygons.  Texture mapping,
                    fog, and all the fragment operations are applied before
                    the fragments are written to the frame buffer.

     GGGGLLLL____SSSSTTTTEEEENNNNCCCCIIIILLLL     Stencil indices are read from the stencil buffer and
                    converted to an internal fixed-point format with an
                    unspecified number of bits to the right of the binary
                    point.  Each fixed-point index is then shifted left by
                    GGGGLLLL____IIIINNNNDDDDEEEEXXXX____SSSSHHHHIIIIFFFFTTTT bits, and added to GGGGLLLL____IIIINNNNDDDDEEEEXXXX____OOOOFFFFFFFFSSSSEEEETTTT.  If
                    GGGGLLLL____IIIINNNNDDDDEEEEXXXX____SSSSHHHHIIIIFFFFTTTT is negative, the shift is to the right.  In
                    either case, zero bits fill otherwise unspecified bit
                    locations in the result.  If GGGGLLLL____MMMMAAAAPPPP____SSSSTTTTEEEENNNNCCCCIIIILLLL is true, the
                    index is replaced with the value that it references in
                    lookup table GGGGLLLL____PPPPIIIIXXXXEEEELLLL____MMMMAAAAPPPP____SSSS____TTTTOOOO____SSSS.  Whether the lookup
                    replacement of the index is done or not, the integer part
                                                     b
                    of the index is then ANDed with 2 -1, where b is the
                    number of bits in the stencil buffer.  The resulting
                    stencil indices are then written to the stencil buffer
                    such that the index read from the ith location of the jth
                    row is written to location (x  + i,y  + j), where (x ,y )
                                                 r      r               r  r
                    is the current raster position.  Only the pixel ownership
                    test, the scissor test, and the stencil writemask affect
                    these write operations.

     The rasterization described thus far assumes pixel zoom factors of 1.0.
     If
     ffffggggllllPPPPiiiixxxxeeeellllZZZZoooooooommmm is used to change the x and y pixel zoom factors, pixels are
     converted to fragments as follows.  If (x , y ) is the current raster
                                              r   r
     position, and a given pixel is in the ith location in the jth row of the
     source pixel rectangle, then fragments are generated for pixels whose
     centers are in the rectangle with corners at

                            (x  + zoom i, y  + zoom j)
                              r       x    r       y

                                        and

                      (x  + zoom (i + 1), y  + zoom (j + 1))
                        r       x          r       y






                                                                        PPPPaaaaggggeeee 3333






ffffggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss((((3333GGGG))))              OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee              ffffggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss((((3333GGGG))))



     where zoom  is the value of GGGGLLLL____ZZZZOOOOOOOOMMMM____XXXX and zoom  is the value of
               x                                   y
     GGGGLLLL____ZZZZOOOOOOOOMMMM____YYYY.

     When GGGGLLLL____IIIINNNNTTTTEEEERRRRLLLLAAAACCCCEEEE____RRRREEEEAAAADDDD____IIIINNNNGGGGRRRR is enabled, every other row of the source
     pixel rectangle is read.  The height of the source pixel rectangle is
     equivalent to 2xheight.  Only rows (y+0,y+2,...) are read and affected by
     pixel transfer and copy operations.

     When GGGGLLLL____IIIINNNNTTTTEEEERRRRLLLLAAAACCCCEEEE____SSSSGGGGIIIIXXXX is enabled, every other row of the destination
     pixel rectangle is modified.  The height of the destination pixel
     rectangle is equivalent to 2xGGGGLLLL____ZZZZOOOOOOOOMMMM____YYYYxheight.  Only rows (y +0,y +2,...)
                                                                 r    r
     of the destination are modified by the copy.

EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
     To copy the color pixel in the lower left corner of the window to the
     current raster position, use

          glCopyPixels(0, 0, 1, 1, GGGGLLLL____CCCCOOOOLLLLOOOORRRR);

NNNNOOOOTTTTEEEESSSS
     Modes specified by ffffggggllllPPPPiiiixxxxeeeellllSSSSttttoooorrrreeee have no effect on the operation of
     ffffggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss.

EEEERRRRRRRROOOORRRRSSSS
     GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____EEEENNNNUUUUMMMM is generated if _t_y_p_e is not an accepted value.

     GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____VVVVAAAALLLLUUUUEEEE is generated if either _w_i_d_t_h or _h_e_i_g_h_t is negative.

     GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is generated if _t_y_p_e is GGGGLLLL____DDDDEEEEPPPPTTTTHHHH and there is no
     depth buffer.

     GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is generated if _t_y_p_e is GGGGLLLL____SSSSTTTTEEEENNNNCCCCIIIILLLL and there is no
     stencil buffer.

     GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is generated if ffffggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss is executed between
     the execution of ffffggggllllBBBBeeeeggggiiiinnnn and the corresponding execution of ffffggggllllEEEEnnnndddd.

AAAASSSSSSSSOOOOCCCCIIIIAAAATTTTEEEEDDDD GGGGEEEETTTTSSSS
     ffffggggllllGGGGeeeetttt with argument GGGGLLLL____CCCCUUUURRRRRRRREEEENNNNTTTT____RRRRAAAASSSSTTTTEEEERRRR____PPPPOOOOSSSSIIIITTTTIIIIOOOONNNN
     ffffggggllllGGGGeeeetttt with argument GGGGLLLL____CCCCUUUURRRRRRRREEEENNNNTTTT____RRRRAAAASSSSTTTTEEEERRRR____PPPPOOOOSSSSIIIITTTTIIIIOOOONNNN____VVVVAAAALLLLIIIIDDDD


MMMMAAAACCCCHHHHIIIINNNNEEEE DDDDEEEEPPPPEEEENNNNDDDDEEEENNNNCCCCIIIIEEEESSSS
     On RealityEngine, RealityEngine2, and VTX systems convolution may not be
     used in the following circumstances:

          1.  When rendering to pixmaps.

          2.  When fragment processing (texturing, depth buffering, alpha
              testing, multisampling, fog) is enabled.





                                                                        PPPPaaaaggggeeee 4444






ffffggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss((((3333GGGG))))              OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee              ffffggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss((((3333GGGG))))



          3.  When histogramming or minmax is enabled.

          4.  When either of the pixel zoom factors has a value other than 1.0
              or -1.0.

     In these cases, ffffggggllllDDDDrrrraaaawwwwPPPPiiiixxxxeeeellllssss and ffffggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss report a
     GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN error and do not transfer any pixels.

     RealityEngine, RealityEngine2, and VTX systems cannot copy pixels from a
     video source (see ffffggggllllXXXXCCCCrrrreeeeaaaatttteeeeGGGGLLLLXXXXVVVViiiiddddeeeeooooSSSSoooouuuurrrrcccceeeeSSSSGGGGIIIIXXXX) when RGBA scale and bias
     are not 1 and 0, respectively, or when any of texturing, alpha or depth
     testing, pixel mapping, multisampling, convolution, histogram, or minmax
     is enabled.  A GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN error will result if any of these
     conditions is true when ffffggggllllCCCCooooppppyyyyPPPPiiiixxxxeeeellllssss is executed.

     The SSSSGGGGIIIIXXXX____iiiinnnntttteeeerrrrllllaaaacccceeee extension is supported only on InfiniteReality
     systems, on RealityEngine, RealityEngine2, and VTX systems, on Octane2
     VPro systems, and on O2 systems.

     The IIIINNNNGGGGRRRR____iiiinnnntttteeeerrrrllllaaaacccceeee____rrrreeeeaaaadddd extension is supported only on Octane2 VPro
     systems, and on O2 systems.


SSSSEEEEEEEE AAAALLLLSSSSOOOO
     ffffggggllllCCCCoooolllloooorrrrTTTTaaaabbbblllleeee, ffffggggllllCCCCoooonnnnvvvvoooolllluuuuttttiiiioooonnnnFFFFiiiilllltttteeeerrrr1111DDDD, ffffggggllllCCCCoooonnnnvvvvoooolllluuuuttttiiiioooonnnnFFFFiiiilllltttteeeerrrr2222DDDD,
     ffffggggllllDDDDeeeepppptttthhhhFFFFuuuunnnncccc, ffffggggllllDDDDrrrraaaawwwwBBBBuuuuffffffffeeeerrrr, ffffggggllllDDDDrrrraaaawwwwPPPPiiiixxxxeeeellllssss, ffffggggllllMMMMaaaattttrrrriiiixxxxMMMMooooddddeeee, ffffggggllllPPPPiiiixxxxeeeellllMMMMaaaapppp,
     ffffggggllllPPPPiiiixxxxeeeellllTTTTrrrraaaannnnssssffffeeeerrrr, ffffggggllllPPPPiiiixxxxeeeellllZZZZoooooooommmm, ffffggggllllRRRRaaaasssstttteeeerrrrPPPPoooossss, ffffggggllllRRRReeeeaaaaddddBBBBuuuuffffffffeeeerrrr,
     ffffggggllllRRRReeeeaaaaddddPPPPiiiixxxxeeeellllssss, ffffggggllllSSSSeeeeppppaaaarrrraaaabbbblllleeeeFFFFiiiilllltttteeeerrrr2222DDDD, ffffggggllllSSSStttteeeennnncccciiiillllFFFFuuuunnnncccc



























                                                                        PPPPaaaaggggeeee 5555